home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / gnu / elispman.lha / elispman / elisp-22 (.txt) < prev    next >
GNU Info File  |  1993-06-01  |  50KB  |  963 lines

  1. This is Info file elisp, produced by Makeinfo-1.55 from the input file
  2. elisp.texi.
  3.    This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for
  4. Emacs Version 19.
  5.    Published by the Free Software Foundation, 675 Massachusetts Avenue,
  6. Cambridge, MA 02139 USA
  7.    Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
  8.    Permission is granted to make and distribute verbatim copies of this
  9. manual provided the copyright notice and this permission notice are
  10. preserved on all copies.
  11.    Permission is granted to copy and distribute modified versions of
  12. this manual under the conditions for verbatim copying, provided that
  13. the entire resulting derived work is distributed under the terms of a
  14. permission notice identical to this one.
  15.    Permission is granted to copy and distribute translations of this
  16. manual into another language, under the above conditions for modified
  17. versions, except that this permission notice may be stated in a
  18. translation approved by the Foundation.
  19. File: elisp,  Node: Skipping Characters,  Prev: List Motion,  Up: Motion
  20. Skipping Characters
  21. -------------------
  22.    The following two functions move point over a specified set of
  23. characters.  For example, they are often used to skip whitespace.  For
  24. related functions, see *Note Motion and Syntax::.
  25.  - Function: skip-chars-forward CHARACTER-SET &optional LIMIT
  26.      This function moves point in the current buffer forward, skipping
  27.      over a given set of characters.  Emacs first examines the
  28.      character following point; if it matches CHARACTER-SET, then point
  29.      is advanced and the next character is examined.  This continues
  30.      until a character is found that does not match.  The function
  31.      returns `nil'.
  32.      The argument CHARACTER-SET is like the inside of a `[...]' in a
  33.      regular expression except that `]' is never special and `\' quotes
  34.      `^', `-' or `\'.  Thus, `"a-zA-Z"' skips over all letters,
  35.      stopping before the first nonletter, and `"^a-zA-Z'" skips
  36.      nonletters stopping before the first letter.  *Note Regular
  37.      Expressions::.
  38.      If LIMIT is supplied (it must be a number or a marker), it
  39.      specifies the maximum position in the buffer that point can be
  40.      skipped to.  Point will stop at or before LIMIT.
  41.      In the following example, point is initially located directly
  42.      before the `T'.  After the form is evaluated, point is located at
  43.      the end of that line (between the `t' of `hat' and the newline).
  44.      The function skips all letters and spaces, but not newlines.
  45.           ---------- Buffer: foo ----------
  46.           I read "-!-The cat in the hat
  47.           comes back" twice.
  48.           ---------- Buffer: foo ----------
  49.           
  50.           (skip-chars-forward "a-zA-Z ")
  51.                => nil
  52.           
  53.           ---------- Buffer: foo ----------
  54.           I read "The cat in the hat-!-
  55.           comes back" twice.
  56.           ---------- Buffer: foo ----------
  57.  - Function: skip-chars-backward CHARACTER-SET &optional LIMIT
  58.      This function moves point backward, skipping characters that match
  59.      CHARACTER-SET.  It just like `skip-chars-forward' except for the
  60.      direction of motion.
  61. File: elisp,  Node: Excursions,  Next: Narrowing,  Prev: Motion,  Up: Positions
  62. Excursions
  63. ==========
  64.    It is often useful to move point "temporarily" within a localized
  65. portion of the program, or to switch buffers temporarily.  This is
  66. called an "excursion", and it is done with the `save-excursion' special
  67. form.  This construct saves the current buffer and its values of point
  68. and the mark so they can be restored after the completion of the
  69. excursion.
  70.    The forms for saving and restoring the configuration of windows are
  71. described elsewhere (see *Note Window Configurations::, and *note Frame
  72. Configurations::.).
  73.  - Special Form: save-excursion FORMS...
  74.      The `save-excursion' special form saves the identity of the current
  75.      buffer and the values of point and the mark in it, evaluates FORMS,
  76.      and finally restores the buffer and its saved values of point and
  77.      the mark.  All three saved values are restored even in case of an
  78.      abnormal exit via throw or error (*note Nonlocal Exits::.).
  79.      The `save-excursion' special form is the standard way to switch
  80.      buffers or move point within one part of a program and avoid
  81.      affecting the rest of the program.  It is used more than 500 times
  82.      in the Lisp sources of Emacs.
  83.      The values of point and the mark for other buffers are not saved by
  84.      `save-excursion', so any changes made to point and the mark in the
  85.      other buffers will remain in effect after `save-excursion' exits.
  86.      Likewise, `save-excursion' does not restore window-buffer
  87.      correspondences altered by functions such as `switch-to-buffer'.
  88.      One way to restore these correspondences, and the selected window,
  89.      is to use `save-window-excursion' inside `save-excursion' (*note
  90.      Window Configurations::.).
  91.      The value returned by `save-excursion' is the result of the last of
  92.      FORMS, or `nil' if no FORMS are given.
  93.           (save-excursion
  94.             FORMS)
  95.           ==
  96.           (let ((old-buf (current-buffer))
  97.                 (old-pnt (point-marker))
  98.                 (old-mark (copy-marker (mark-marker))))
  99.             (unwind-protect
  100.                 (progn FORMS)
  101.               (set-buffer old-buf)
  102.               (goto-char old-pnt)
  103.               (set-marker (mark-marker) old-mark)))
  104. File: elisp,  Node: Narrowing,  Prev: Excursions,  Up: Positions
  105. Narrowing
  106. =========
  107.    "Narrowing" means limiting the text addressable by Emacs editing
  108. commands to a limited range of characters in a buffer.  The text that
  109. remains addressable is called the "accessible portion" of the buffer.
  110.    Narrowing is specified with two buffer positions which become the
  111. beginning and end of the accessible portion.  For most editing commands
  112. these positions replace the values of the beginning and end of the
  113. buffer.  While narrowing is in effect, no text outside the accessible
  114. portion is displayed, and point cannot move outside the accessible
  115. portion.
  116.    Values such as positions or line numbers which usually count from the
  117. beginning of the buffer continue to do so, but the functions which use
  118. them will refuse to operate on text that is inaccessible.
  119.    The commands for saving buffers are unaffected by narrowing; the
  120. entire buffer is saved regardless of the any narrowing.
  121.  - Command: narrow-to-region START END
  122.      This function sets the accessible portion of the current buffer to
  123.      start at START and end at END.  Both arguments should be character
  124.      positions.
  125.      In an interactive call, START and END are set to the bounds of the
  126.      current region (point and the mark, with the smallest first).
  127.  - Command: narrow-to-page MOVE-COUNT
  128.      This function sets the accessible portion of the current buffer to
  129.      include just the current page.  An optional first argument
  130.      MOVE-COUNT non-`nil' means to move forward or backward by
  131.      MOVE-COUNT pages and then narrow.
  132.      In an interactive call, MOVE-COUNT is set to the numeric prefix
  133.      argument.
  134.  - Command: widen
  135.      This function cancels any narrowing in the current buffer, so that
  136.      the entire contents are accessible.  This is called "widening".
  137.      It is equivalent to the following expression:
  138.           (narrow-to-region 1 (1+ (buffer-size)))
  139.  - Special Form: save-restriction BODY...
  140.      This special form saves the current bounds of the accessible
  141.      portion, evaluates the BODY forms, and finally restores the saved
  142.      bounds, thus restoring the same state of narrowing (or absence
  143.      thereof) formerly in effect.  The state of narrowing is restored
  144.      even in the event of an abnormal exit via throw or error (*note
  145.      Nonlocal Exits::.).  Therefore, this construct is a clean way to
  146.      narrow a buffer temporarily.
  147.      The value returned by `save-restriction' is that returned by the
  148.      last form in BODY, or `nil' if no body forms were given.
  149.      *Caution:* it is easy to make a mistake when using the
  150.      `save-restriction' function.  Read the entire description here
  151.      before you try it.
  152.      If BODY changes the current buffer, `save-restriction' still
  153.      restores the restrictions on the original buffer (the buffer they
  154.      came from), but it does not restore the identity of the current
  155.      buffer.
  156.      Point and the mark are *not* restored by this special form; use
  157.      `save-excursion' for that.  If you use both `save-restriction' and
  158.      `save-excursion' together, `save-excursion' should come first (on
  159.      the outside).  Otherwise, the old point value would be restored
  160.      with temporary narrowing still in effect.  If the old point value
  161.      were outside the limits of the temporary narrowing, this would
  162.      fail to restore it accurately.
  163.      The `save-restriction' special form records the values of the
  164.      beginning and end of the accessible portion as distances from the
  165.      beginning and end of the buffer.  In other words, it records the
  166.      amount of inaccessible text before and after the accessible
  167.      portion.
  168.      This technique yields correct results if BODY does further
  169.      narrowing.  However, `save-restriction' can become confused if they
  170.      widen and then make changes outside the area of the saved
  171.      narrowing.  When this is what you want to do, `save-restriction'
  172.      is not the right tool for the job.  Here is what you must use
  173.      instead:
  174.           (let ((beg (point-min-marker))
  175.                 (end (point-max-marker)))
  176.             (unwind-protect
  177.                 (progn BODY)
  178.               (save-excursion
  179.                 (set-buffer (marker-buffer beg))
  180.                 (narrow-to-region beg end))))
  181.      Here is a simple example of correct use of `save-restriction':
  182.           ---------- Buffer: foo ----------
  183.           This is the contents of foo
  184.           This is the contents of foo
  185.           This is the contents of foo-!-
  186.           ---------- Buffer: foo ----------
  187.           
  188.           (save-excursion
  189.             (save-restriction
  190.               (goto-char 1)
  191.               (forward-line 2)
  192.               (narrow-to-region 1 (point))
  193.               (goto-char (point-min))
  194.               (replace-string "foo" "bar")))
  195.           
  196.           ---------- Buffer: foo ----------
  197.           This is the contents of bar
  198.           This is the contents of bar
  199.           This is the contents of foo-!-
  200.           ---------- Buffer: foo ----------
  201. File: elisp,  Node: Markers,  Next: Text,  Prev: Positions,  Up: Top
  202. Markers
  203. *******
  204.    A "marker" is a Lisp object used to specify a position in a buffer
  205. relative to the surrounding text.  A marker changes its offset from the
  206. beginning of the buffer automatically whenever text is inserted or
  207. deleted, so that it stays with the two characters on either side of it.
  208. * Menu:
  209. * Overview of Markers::      The components of a marker, and how it relocates.
  210. * Predicates on Markers::    Testing whether an object is a marker.
  211. * Creating Markers::         Making empty markers or markers at certain places.
  212. * Information from Markers:: Finding the marker's buffer or character position.
  213. * Changing Markers::         Moving the marker to a new buffer or position.
  214. * The Mark::                 How "the mark" is implemented with a marker.
  215. * The Region::               How to access "the region".
  216. File: elisp,  Node: Overview of Markers,  Next: Predicates on Markers,  Prev: Markers,  Up: Markers
  217. Overview of Markers
  218. ===================
  219.    A marker specifies a buffer and a position in that buffer.  The
  220. marker can be used to represent a position in the functions that
  221. require one, just as an integer could be used.  *Note Positions::, for
  222. a complete description of positions.
  223.    A marker has two attributes: the marker position, and the marker
  224. buffer.  The marker position is an integer which is equivalent (at the
  225. moment) to the marker as a position in that buffer; however, as text is
  226. inserted or deleted in the buffer, the marker is relocated, so that its
  227. integer equivalent changes.  The idea is that a marker positioned
  228. between two characters in a buffer will remain between those two
  229. characters despite any changes made to the contents of the buffer; thus,
  230. a marker's offset from the beginning of a buffer may change often during
  231. the life of the marker.
  232.    If the text around a marker is deleted, the marker is repositioned
  233. between the characters immediately before and after the deleted text.
  234. If text is inserted at the position of a marker, the marker remains in
  235. front of the new text unless it is inserted with `insert-before-markers'
  236. (*note Insertion::.).  When text is inserted or deleted somewhere
  237. before the marker position (not next to the marker), the marker moves
  238. back and forth with the two neighboring characters.
  239.    When a buffer is modified, all of its markers must be checked so that
  240. they can be relocated if necessary.  This slows processing in a buffer
  241. with a large number of markers.  For this reason, it is a good idea to
  242. make a marker point nowhere if you are sure you don't need it any more.
  243. Unreferenced markers will eventually be garbage collected, but until
  244. then will continue to be updated if they do point somewhere.
  245.    Because it is quite common to perform arithmetic operations on a
  246. marker position, most of the arithmetic operations (including `+' and
  247. `-') accept markers as arguments.  In such cases, the current position
  248. of the marker is used.
  249.    Here are examples of creating markers, setting markers, and moving
  250. point to markers:
  251.      ;; Make a new marker that initially does not point anywhere:
  252.      (setq m1 (make-marker))
  253.           => #<marker in no buffer>
  254.      
  255.      ;; Set `m1' to point between the 100th and 101st characters
  256.      ;;   in the current buffer:
  257.      (set-marker m1 100)
  258.           => #<marker at 100 in markers.texi>
  259.      
  260.      ;; Now insert one character at the beginning of the buffer:
  261.      (goto-char (point-min))
  262.           => 1
  263.      (insert "Q")
  264.           => nil
  265.      
  266.      ;; `m1' is updated appropriately.
  267.      m1
  268.           => #<marker at 101 in markers.texi>
  269.      
  270.      ;; Two markers that point to the same position
  271.      ;;   are not `eq', but they are `equal'.
  272.      (setq m2 (copy-marker m1))
  273.           => #<marker at 101 in markers.texi>
  274.      (eq m1 m2)
  275.           => nil
  276.      (equal m1 m2)
  277.           => t
  278.      
  279.      ;; When you are finished using a marker, make it point nowhere.
  280.      (set-marker m1 nil)
  281.           => #<marker in no buffer>
  282. File: elisp,  Node: Predicates on Markers,  Next: Creating Markers,  Prev: Overview of Markers,  Up: Markers
  283. Predicates on Markers
  284. =====================
  285.    You can test an object to see whether it is a marker, or whether it
  286. is either an integer or a marker.  The latter test is useful when you
  287. are using the arithmetic functions that work with both markers and
  288. integers.
  289.  - Function: markerp OBJECT
  290.      This function returns `t' if OBJECT is a marker, `nil' otherwise.
  291.      In particular, integers are not markers, even though many
  292.      functions will accept either a marker or an integer.
  293.  - Function: integer-or-marker-p OBJECT
  294.      This function returns `t' if OBJECT is an integer or a marker,
  295.      `nil' otherwise.
  296.  - Function: number-or-marker-p OBJECT
  297.      This function returns `t' if OBJECT is a number (of any type) or a
  298.      marker, `nil' otherwise.
  299. File: elisp,  Node: Creating Markers,  Next: Information from Markers,  Prev: Predicates on Markers,  Up: Markers
  300. Functions That Create Markers
  301. =============================
  302.    When you create a new marker, you can make it point nowhere, or point
  303. to the present position of point, or to the beginning or end of the
  304. accessible portion of the buffer, or to the same place as another given
  305. marker.
  306.  - Function: make-marker
  307.      This functions returns a newly allocated marker that does not point
  308.      anywhere.
  309.           (make-marker)
  310.                => #<marker in no buffer>
  311.  - Function: point-marker
  312.      This function returns a new marker that points to the present
  313.      position of point in the current buffer.  *Note Point::.  For an
  314.      example, see `copy-marker', below.
  315.  - Function: point-min-marker
  316.      This function returns a new marker that points to the beginning of
  317.      the accessible portion of the buffer.  This will be the beginning
  318.      of the buffer unless narrowing is in effect.  *Note Narrowing::.
  319.  - Function: point-max-marker
  320.      This function returns a new marker that points to the end of the
  321.      accessible portion of the buffer.  This will be the end of the
  322.      buffer unless narrowing is in effect.  *Note Narrowing::.
  323.      Here are examples of this function and `point-min-marker', shown in
  324.      a buffer containing a version of the source file for the text of
  325.      this chapter.
  326.           (point-min-marker)
  327.                => #<marker at 1 in markers.texi>
  328.           (point-max-marker)
  329.                => #<marker at 15573 in markers.texi>
  330.           
  331.           (narrow-to-region 100 200)
  332.                => nil
  333.           (point-min-marker)
  334.                => #<marker at 100 in markers.texi>
  335.           (point-max-marker)
  336.                => #<marker at 200 in markers.texi>
  337.  - Function: copy-marker MARKER-OR-INTEGER
  338.      If passed a marker as its argument, `copy-marker' returns a new
  339.      marker that points to the same place and the same buffer as does
  340.      MARKER-OR-INTEGER.  If passed an integer as its argument,
  341.      `copy-marker' returns a new marker that points to position
  342.      MARKER-OR-INTEGER in the current buffer.
  343.      If passed an argument that is an integer whose value is less than
  344.      1, `copy-marker' returns a new marker that points to the beginning
  345.      of the current buffer.  If passed an argument that is an integer
  346.      whose value is greater than the length of the buffer, then
  347.      `copy-marker' returns a new marker that points to the end of the
  348.      buffer.
  349.      An error is signaled if MARKER is neither a marker nor an integer.
  350.           (setq p (point-marker))
  351.                => #<marker at 2139 in markers.texi>
  352.           
  353.           (setq q (copy-marker p))
  354.                => #<marker at 2139 in markers.texi>
  355.           
  356.           (eq p q)
  357.                => nil
  358.           
  359.           (equal p q)
  360.                => t
  361.           
  362.           (copy-marker 0)
  363.                => #<marker at 1 in markers.texi>
  364.           
  365.           (copy-marker 20000)
  366.                => #<marker at 7572 in markers.texi>
  367. File: elisp,  Node: Information from Markers,  Next: Changing Markers,  Prev: Creating Markers,  Up: Markers
  368. Information from Markers
  369. ========================
  370.    This section describes the functions for accessing the components of
  371. a marker object.
  372.  - Function: marker-position MARKER
  373.      This function returns the position that MARKER points to, or `nil'
  374.      if it points nowhere.
  375.  - Function: marker-buffer MARKER
  376.      This function returns the buffer that MARKER points into, or `nil'
  377.      if it points nowhere.
  378.           (setq m (make-marker))
  379.                => #<marker in no buffer>
  380.           (marker-position m)
  381.                => nil
  382.           (marker-buffer m)
  383.                => nil
  384.           
  385.           (set-marker m 3770 (current-buffer))
  386.                => #<marker at 3770 in markers.texi>
  387.           (marker-buffer m)
  388.                => #<buffer markers.texi>
  389.           (marker-position m)
  390.                => 3770
  391.    Two distinct markers will be found `equal' (even though not `eq') to
  392. each other if they have the same position and buffer, or if they both
  393. point nowhere.
  394. File: elisp,  Node: Changing Markers,  Next: The Mark,  Prev: Information from Markers,  Up: Markers
  395. Changing Markers
  396. ================
  397.    This section describes how to change the position of an existing
  398. marker.  When you do this, be sure you know whether the marker is used
  399. outside of your program, and, if so, what effects will result from
  400. moving it--otherwise, confusing things may happen in other parts of
  401. Emacs.
  402.  - Function: set-marker MARKER POSITION &optional BUFFER
  403.      This function moves MARKER to POSITION in BUFFER.  If BUFFER is
  404.      not provided, it defaults to the current buffer.
  405.      If POSITION is less than 1, `set-marker' moves marker to the
  406.      beginning of the buffer.  If the value of POSITION is greater than
  407.      the size of the buffer, `set-marker' moves marker to the end of
  408.      the buffer.  If POSITION is `nil' or a marker that points nowhere,
  409.      then MARKER is set to point nowhere.
  410.      The value returned is MARKER.
  411.           (setq m (point-marker))
  412.                => #<marker at 4714 in markers.texi>
  413.           (set-marker m 55)
  414.                => #<marker at 55 in markers.texi>
  415.           (setq b (get-buffer "foo"))
  416.                => #<buffer foo>
  417.           (set-marker m 0 b)
  418.                => #<marker at 1 in foo>
  419.  - Function: move-marker MARKER POSITION &optional BUFFER
  420.      This is another name for `set-marker'.
  421. File: elisp,  Node: The Mark,  Next: The Region,  Prev: Changing Markers,  Up: Markers
  422. The Mark
  423. ========
  424.    A special marker in each buffer is designated "the mark".  It
  425. records a position for the user for the sake of commands such as `C-w'
  426. and `C-x TAB'.  Lisp programs should set the mark only to values that
  427. have a potential use to the user, and never for their own internal
  428. purposes.  For example, the `replace-regexp' command sets the mark to
  429. the value of point before doing any replacements, because this enables
  430. the user to move back there conveniently after the replace is finished.
  431.    Many commands are designed so that when called interactively they
  432. operate on the text between point and the mark.  If you are writing such
  433. a command, don't examine the mark directly; instead, use `interactive'
  434. with the `r' specification.  This will provide the values of point and
  435. the mark as arguments to the command in an interactive call, but will
  436. permit other Lisp programs to specify arguments explicitly.  *Note
  437. Interactive Codes::.
  438.    Each buffer has its own value of the mark that is independent of the
  439. value of the mark in other buffers.  When a buffer is created, the mark
  440. exists but does not point anywhere.  We consider this state as "the
  441. absence of a mark in that buffer".
  442.    Once the mark "exists" in a buffer, it normally never ceases to
  443. exist.  However, it may become "inactive", if Transient Mark mode is
  444. enabled.  The variable `mark-active', which is always local in all
  445. buffers, indicates whether the mark is active: non-`nil' means yes.  A
  446. command can request deactivation of the mark upon return to the editor
  447. command loop by setting `deactivate-mark' to a non-`nil' value (but
  448. this deactivation only follows if Transient Mark mode is enabled).
  449.    The main motivation for using Transient Mark mode is that this mode
  450. also enables highlighting of the region when the mark is active.  *Note
  451. Emacs Display::.
  452.    In addition to the mark, each buffer has a "mark ring" which is a
  453. list of markers that are the previous values of the mark.  When editing
  454. commands change the mark, they should normally save the old value of the
  455. mark on the mark ring.  The mark ring may contain no more than the
  456. maximum number of entries specified by the variable `mark-ring-max';
  457. excess entries are discarded on a first-in-first-out basis.
  458.  - Function: mark &optional FORCE
  459.      This function returns the position of the current buffer's mark as
  460.      an integer.
  461.      Normally, if the mark is inactive `mark' signals an error.
  462.      However, if FORCE is non-`nil', then it returns the mark position
  463.      anyway--or `nil', if the mark is not yet set for this buffer.
  464.  - Function: mark-marker
  465.      This function returns the current buffer's mark.  This is the very
  466.      marker which records the mark location inside Emacs, not a copy.
  467.      Therefore, changing this marker's position will directly affect
  468.      the position of the mark.  Don't do it unless that is the effect
  469.      you want.
  470.           (setq m (mark-marker))
  471.                => #<marker at 3420 in markers.texi>
  472.           (set-marker m 100)
  473.                => #<marker at 100 in markers.texi>
  474.           (mark-marker)
  475.                => #<marker at 100 in markers.texi>
  476.      Like any marker, this marker can be set to point at any buffer you
  477.      like.  We don't recommend that you make it point at any buffer
  478.      other than the one of which it is the mark.  If you do, it will
  479.      yield perfectly consistent, if rather odd, results.
  480.  - Function: set-mark POSITION
  481.      This function sets the mark to POSITION, and activates the mark.
  482.      The old value of the mark is *not* pushed onto the mark ring.
  483.      *Please note:* use this function only if you want the user to see
  484.      that the mark has moved, and you want the previous mark position to
  485.      be lost.  Normally, when a new mark is set, the old one should go
  486.      on the `mark-ring'.  For this reason, most applications should use
  487.      `push-mark' and `pop-mark', not `set-mark'.
  488.      Novice Emacs Lisp programmers often try to use the mark for the
  489.      wrong purposes.  The mark saves a location for the user's
  490.      convenience.  An editing command should not alter the mark unless
  491.      altering the mark is part of the user-level functionality of the
  492.      command.  (And, in that case, this effect should be documented.)
  493.      To remember a location for internal use in the Lisp program, store
  494.      it in a Lisp variable.  For example:
  495.           (let ((beg (point)))
  496.             (forward-line 1)
  497.             (delete-region beg (point))).
  498.  - Variable: mark-ring
  499.      The value of this buffer-local variable is the list of saved former
  500.      marks of the current buffer, most recent first.
  501.           mark-ring
  502.           => (#<marker at 11050 in markers.texi>
  503.               #<marker at 10832 in markers.texi>
  504.               ...)
  505.  - User Option: mark-ring-max
  506.      The value of this variable is the maximum size of `mark-ring'.  If
  507.      more marks than this are pushed onto the `mark-ring', it discards
  508.      marks on a first-in, first-out basis.
  509.  - Function: push-mark &optional POSITION NOMSG ACTIVATE
  510.      This function sets the current buffer's mark to POSITION, and
  511.      pushes a copy of the previous mark onto `mark-ring'.  If POSITION
  512.      is `nil', then the value of point is used.  `push-mark' returns
  513.      `nil'.
  514.      The function `push-mark' normally *does not* activate the mark.
  515.      To do that, specify `t' for the argument ACTIVATE.
  516.      A `Mark set' message is displayed unless NOMSG is non-`nil'.
  517.  - Function: pop-mark
  518.      This function pops off the top element of `mark-ring' and makes
  519.      that mark become the buffer's actual mark.  This does not change
  520.      the buffer's point, and does nothing if `mark-ring' is empty.  It
  521.      deactivates the mark.
  522.      The return value is not useful.
  523.  - User Option: transient-mark-mode
  524.      This variable enables Transient Mark mode, in which every
  525.      buffer-modifying primitive sets `deactivate-mark'.  The consequence
  526.      of this is that commands that modify the buffer normally cause the
  527.      mark to become inactive.
  528.  - Variable: deactivate-mark
  529.      If an editor command sets this variable non-`nil', then the editor
  530.      command loop deactivates the mark after the command returns.
  531.  - Variable: mark-active
  532.      The mark is active when this variable is non-`nil'.  This variable
  533.      is always local in each buffer.
  534.  - Variable: activate-mark-hook
  535.  - Variable: deactivate-mark-hook
  536.      These normal hooks are run, respectively, when the mark becomes
  537.      active and when it becomes inactive.  The hook
  538.      `activate-mark-hook' is also run at the end of a command if the
  539.      mark is active and the region may have changed.
  540. File: elisp,  Node: The Region,  Prev: The Mark,  Up: Markers
  541. The Region
  542. ==========
  543.    The text between point and the mark is known as "the region".
  544. Various functions operate on text delimited by point and the mark, but
  545. only those functions specifically related to the region itself are
  546. described here.
  547.  - Function: region-beginning
  548.      This function returns the position of the beginning of the region
  549.      (as an integer).  This is the position of either point or the mark,
  550.      whichever is smaller.
  551.      If the mark does not point anywhere, an error is signaled.
  552.  - Function: region-end
  553.      This function returns the position of the end of the region (as an
  554.      integer).  This is the position of either point or the mark,
  555.      whichever is larger.
  556.      If the mark does not point anywhere, an error is signaled.
  557.    Few programs need to use the `region-beginning' and `region-end'
  558. functions.  A command designed to operate on a region should instead
  559. use `interactive' with the `r' specification, so that the same function
  560. can be called with explicit bounds arguments from programs.  (*Note
  561. Interactive Codes::.)
  562. File: elisp,  Node: Text,  Next: Searching and Matching,  Prev: Markers,  Up: Top
  563.    This chapter describes the functions that deal with the text in a
  564. buffer.  Most examine, insert or delete text in the current buffer,
  565. often in the vicinity of point.  Many are interactive.  All the
  566. functions that change the text provide for undoing the changes (*note
  567. Undo::.).
  568.    Many text-related functions operate on a region of text defined by
  569. two buffer positions passed in arguments named START and END.  These
  570. arguments should be either markers (*note Markers::.) or or numeric
  571. character positions (*note Positions::.).  The order of these arguments
  572. does not matter; it is all right for START to be the end of the region
  573. and END the beginning.  For example, `(delete-region 1 10)' and
  574. `(delete-region 10 1)' perform identically.  An `args-out-of-range'
  575. error is signaled if either START or END is outside the accessible
  576. portion of the buffer.  In an interactive call, point and the mark are
  577. used for these arguments.
  578.    Throughout this chapter, "text" refers to the characters in the
  579. buffer.
  580. * Menu:
  581. * Near Point::       Examining text in the vicinity of point.
  582. * Buffer Contents::  Examining text in a general fashion.
  583. * Comparing Text::   Comparing substrings of buffers.
  584. * Insertion::        Adding new text to a buffer.
  585. * Commands for Insertion::  User-level commands to insert text.
  586. * Deletion::         Removing text from a buffer.
  587. * User-Level Deletion::     User-level commands to delete text.
  588. * The Kill Ring::    Where removed text sometimes is saved for later use.
  589. * Undo::             Undoing changes to the text of a buffer.
  590. * Maintaining Undo:: How to enable and disable undo information.
  591.             How to control how much information is kept.
  592. * Auto Filling::     How auto-fill mode is implemented to break lines.
  593. * Filling::          Functions for explicit filling.
  594. * Sorting::          Functions for sorting parts of the buffer.
  595. * Indentation::      Functions to insert or adjust indentation.
  596. * Columns::          Computing horizontal positions, and using them.
  597. * Case Changes::     Case conversion of parts of the buffer.
  598. * Text Properties::  Assigning Lisp property lists to text characters.
  599. * Substitution::     Replacing a given character wherever it appears.
  600. * Underlining::      Inserting or deleting underlining-by-overstrike.
  601. * Registers::        How registers are implemented.  Accessing the text or
  602.                        position stored in a register.
  603. * Change Hooks::     Supplying functions to be run when text is changed.
  604. File: elisp,  Node: Near Point,  Next: Buffer Contents,  Up: Text
  605. Examining Text Near Point
  606. =========================
  607.    Many functions are provided to look at the characters around point.
  608. Several simple functions are described here.  See also `looking-at' in
  609. *Note Regexp Search::.
  610.  - Function: char-after POSITION
  611.      This function returns the character in the current buffer at (i.e.,
  612.      immediately after) position POSITION.  If POSITION is out of range
  613.      for this purpose, either before the beginning of the buffer, or at
  614.      or beyond the end, then the value is `nil'.
  615.      Remember that point is always between characters, and the terminal
  616.      cursor normally appears over the character following point.
  617.      Therefore, the character returned by `char-after' is the character
  618.      the cursor is over.
  619.      In the following example, assume that the first character in the
  620.      buffer is `@':
  621.           (char-to-string (char-after 1))
  622.                => "@"
  623.  - Function: following-char
  624.      This function returns the character following point in the current
  625.      buffer.  This is similar to `(char-after (point))'.  However, if
  626.      point is at the end of the buffer, then the result of
  627.      `following-char' is 0.
  628.      In this example, point is between the `a' and the `c'.
  629.           ---------- Buffer: foo ----------
  630.           Gentlemen may cry ``Pea-!-ce! Peace!,''
  631.           but there is no peace.
  632.           ---------- Buffer: foo ----------
  633.           
  634.           (char-to-string (preceding-char))
  635.                => "a"
  636.           (char-to-string (following-char))
  637.                => "c"
  638.  - Function: preceding-char
  639.      This function returns the character preceding point in the current
  640.      buffer.  See above, under `following-char', for an example.  If
  641.      point is at the beginning of the buffer, then the result of
  642.      `preceding-char' is 0.
  643.  - Function: bobp
  644.      This function returns `t' if point is at the beginning of the
  645.      buffer.  If narrowing is in effect, this means the beginning of the
  646.      accessible portion of the text.  See also `point-min' in *Note
  647.      Point::.
  648.  - Function: eobp
  649.      This function returns `t' if point is at the end of the buffer.
  650.      If narrowing is in effect, this means the end of accessible
  651.      portion of the text.  See also `point-max' in *Note Point::.
  652.  - Function: bolp
  653.      This function returns `t' if point is at the beginning of a line.
  654.      *Note Text Lines::.
  655.  - Function: eolp
  656.      This function returns `t' if point is at the end of a line.  The
  657.      end of the buffer is always considered the end of a line.
  658. File: elisp,  Node: Buffer Contents,  Next: Comparing Text,  Prev: Near Point,  Up: Text
  659. Examining Buffer Contents
  660. =========================
  661.    This section describes two functions that allow a Lisp program to
  662. convert any portion of the text in the buffer into a string.
  663.  - Function: buffer-substring START END
  664.      This function returns a string containing a copy of the text of the
  665.      region defined by positions START and END in the current buffer.
  666.      If the arguments are not positions in the accessible portion of
  667.      the buffer, Emacs signals an `args-out-of-range' error.
  668.      It is not necessary for START to be less than END; the arguments
  669.      can be given in either order.  But most often the smaller argument
  670.      is written first.
  671.           ---------- Buffer: foo ----------
  672.           This is the contents of buffer foo
  673.           
  674.           ---------- Buffer: foo ----------
  675.           
  676.           (buffer-substring 1 10)
  677.           => "This is t"
  678.           (buffer-substring (point-max) 10)
  679.           => "he contents of buffer foo
  680.           "
  681.  - Function: buffer-string
  682.      This function returns the contents of the accessible portion of the
  683.      current buffer as a string.  This is the portion between
  684.      `(point-min)' and `(point-max)' (*note Narrowing::.).
  685.           ---------- Buffer: foo ----------
  686.           This is the contents of buffer foo
  687.           
  688.           ---------- Buffer: foo ----------
  689.           
  690.           (buffer-string)
  691.                => "This is the contents of buffer foo
  692.           "
  693. File: elisp,  Node: Comparing Text,  Next: Insertion,  Prev: Buffer Contents,  Up: Text
  694. Comparing Text
  695. ==============
  696.    This function lets you compare portions of the text in a buffer,
  697. without copying them into strings first.
  698.  - Function: compare-buffer-substrings BUFFER1 START1 END1 BUFFER2
  699.           START2 END2
  700.      This function lets you compare two substrings of the same buffer
  701.      or two different buffers.  The first three arguments specify one
  702.      substring, giving a buffer and two positions within the buffer.
  703.      The last three arguments specify the other substring in the same
  704.      way.  You can use `nil' for BUFFER1, BUFFER2 or both to stand for
  705.      the current buffer.
  706.      The value is negative if the first substring is less, positive if
  707.      the first is greater, and zero if they are equal.  The absolute
  708.      value of the result is one plus the index of the first differing
  709.      characters within the substrings.
  710.      This function ignores case when comparing characters if
  711.      `case-fold-search' is non-`nil'.
  712.      Suppose the current buffer contains the text `foobarbar
  713.      haha!rara!'; then in this example the two substrings are `rbar '
  714.      and `rara!'.  The value is 2 because the first substring is greater
  715.      at the second character.
  716.           (compare-buffer-substring nil 6 11 nil 16 21)
  717.                => 2
  718.      This function does not exist in Emacs version 18 and earlier.
  719. File: elisp,  Node: Insertion,  Next: Commands for Insertion,  Prev: Comparing Text,  Up: Text
  720. Insertion
  721. =========
  722.    Insertion takes place at point.  Markers pointing at positions after
  723. the insertion point are relocated with the surrounding text (*note
  724. Markers::.).  When a marker points at the place of insertion, it is
  725. normally not relocated, so that it points to the beginning of the
  726. inserted text; however, when `insert-before-markers' is used, all such
  727. markers are relocated to point after the inserted text.
  728.    Point may end up either before or after inserted text, depending on
  729. the function used.  If point is left after the inserted text, we speak
  730. of insertion "before point".
  731.    Each of these functions signals an error if the current buffer is
  732. read-only.
  733.  - Function: insert &rest ARGS
  734.      This function inserts the strings and/or characters ARGS into the
  735.      current buffer, at point, moving point forward.  An error is
  736.      signaled unless all ARGS are either strings or characters.  The
  737.      value is `nil'.
  738.  - Function: insert-before-markers &rest ARGS
  739.      This function inserts the strings and/or characters ARGS into the
  740.      current buffer, at point, moving point forward.  An error is
  741.      signaled unless all ARGS are either strings or characters.  The
  742.      value is `nil'.
  743.      This function is unlike the other insertion functions in that a
  744.      marker whose position initially equals point is relocated to come
  745.      after the newly inserted text.
  746.  - Function: insert-char CHARACTER COUNT
  747.      This function inserts COUNT instances of CHARACTER into the
  748.      current buffer before point.  COUNT must be a number, and
  749.      CHARACTER must be a character.  The value is `nil'.
  750.  - Function: insert-buffer-substring FROM-BUFFER-OR-NAME &optional
  751.           START END
  752.      This function inserts a substring of the contents of buffer
  753.      FROM-BUFFER-OR-NAME (which must already exist) into the current
  754.      buffer before point.  The text inserted consists of the characters
  755.      in the region defined by START and END (These arguments default to
  756.      the beginning and end of the accessible portion of that buffer).
  757.      The function returns `nil'.
  758.      In this example, the form is executed with buffer `bar' as the
  759.      current buffer.  We assume that buffer `bar' is initially empty.
  760.           ---------- Buffer: foo ----------
  761.           We hold these truths to be self-evident, that all
  762.           ---------- Buffer: foo ----------
  763.           
  764.           (insert-buffer-substring "foo" 1 20)
  765.                => nil
  766.           
  767.           ---------- Buffer: bar ----------
  768.           We hold these truth
  769.           ---------- Buffer: bar ----------
  770. File: elisp,  Node: Commands for Insertion,  Next: Deletion,  Prev: Insertion,  Up: Text
  771. User-Level Insertion Commands
  772. =============================
  773.    This section describes higher-level commands for inserting text,
  774. commands intended primarily for the user but useful also in Lisp
  775. programs.
  776.  - Command: insert-buffer FROM-BUFFER-OR-NAME
  777.      This function inserts the entire contents of FROM-BUFFER-OR-NAME
  778.      (which must exist) into the current buffer after point.  It leaves
  779.      the mark after the inserted text.  The value is `nil'.
  780.  - Command: self-insert-command COUNT
  781.      This function inserts the last character typed COUNT times and
  782.      returns `nil'.  Most printing characters are bound to this
  783.      command.  In routine use, `self-insert-command' is the most
  784.      frequently called function in Emacs, but programs rarely use it
  785.      except to install it on a keymap.
  786.      In an interactive call, COUNT is the numeric prefix argument.
  787.      This function calls `auto-fill-function' if the current column
  788.      number is greater than the value of `fill-column' and the character
  789.      inserted is a space (*note Auto Filling::.).
  790.      This function performs abbrev expansion if Abbrev mode is enabled
  791.      and the inserted character does not have word-constituent syntax.
  792.      (*Note Abbrevs::, and *Note Syntax Class Table::.)
  793.      This function is also responsible for calling
  794.      `blink-paren-function' when the inserted character has close
  795.      parenthesis syntax (*note Blinking::.).
  796.  - Command: newline &optional NUMBER-OF-NEWLINES
  797.      This function inserts newlines into the current buffer before
  798.      point.  If NUMBER-OF-NEWLINES is supplied, that many newline
  799.      characters are inserted.
  800.      In Auto Fill mode, `newline' can break the preceding line if
  801.      NUMBER-OF-NEWLINES is not supplied.  When this happens, it
  802.      actually inserts two newlines at different places: one at point,
  803.      and another earlier in the line.  `newline' does not auto-fill if
  804.      NUMBER-OF-NEWLINES is non-`nil'.
  805.      The value returned is `nil'.  In an interactive call, COUNT is the
  806.      numeric prefix argument.
  807.  - Command: split-line
  808.      This function splits the current line, moving the portion of the
  809.      line after point down vertically, so that it is on the next line
  810.      directly below where it was before.  Whitespace is inserted as
  811.      needed at the beginning of the lower line, using the `indent-to'
  812.      function.  `split-line' returns the position of point.
  813.      Programs hardly ever use this function.
  814.  - Variable: overwrite-mode
  815.      This variable controls whether overwrite mode is in effect: a
  816.      non-`nil' value enables the mode.  It is automatically made
  817.      buffer-local when set in any fashion.
  818. File: elisp,  Node: Deletion,  Next: User-Level Deletion,  Prev: Commands for Insertion,  Up: Text
  819. Deletion of Text
  820. ================
  821.    All of the deletion functions operate on the current buffer, and all
  822. return a value of `nil'.  In addition to these functions, you can also
  823. delete text using the "kill" functions that save it in the kill ring;
  824. some of these functions save text in the kill ring in some cases but
  825. not in the usual case.  *Note The Kill Ring::.
  826.  - Function: erase-buffer
  827.      This function deletes the entire text of the current buffer,
  828.      leaving it empty.  If the buffer is read-only, it signals a
  829.      `buffer-read-only' error.  Otherwise, it deletes the text without
  830.      asking for any confirmation.  The value is always `nil'.
  831.      Normally, deleting a large amount of text from a buffer inhibits
  832.      further auto-saving of that buffer "because it has shrunk".
  833.      However, `erase-buffer' does not do this, the idea being that the
  834.      future text is not really related to the former text, and its size
  835.      should not be compared with that of the former text.
  836.  - Command: delete-region START END
  837.      This function deletes the text in the current buffer in the region
  838.      defined by START and END.  The value is `nil'.
  839.  - Command: delete-char COUNT &optional KILLP
  840.      This function deletes COUNT characters directly after point, or
  841.      before point if COUNT is negative.  If KILLP is non-`nil', then it
  842.      saves the deleted characters in the kill ring.
  843.      In an interactive call, COUNT is the numeric prefix argument, and
  844.      KILLP is the unprocessed prefix argument.  Therefore, if a prefix
  845.      argument is supplied, the text is saved in the kill ring.  If no
  846.      prefix argument is supplied, then one character is deleted, but
  847.      not saved in the kill ring.
  848.      The value returned is always `nil'.
  849.  - Command: delete-backward-char COUNT &optional KILLP
  850.      This function deletes COUNT characters directly before point, or
  851.      after point if COUNT is negative.  If KILLP is non-`nil', then it
  852.      saves the deleted characters in the kill ring.
  853.      In an interactive call, COUNT is the numeric prefix argument, and
  854.      KILLP is the unprocessed prefix argument.  Therefore, if a prefix
  855.      argument is supplied, the text is saved in the kill ring.  If no
  856.      prefix argument is supplied, then one character is deleted, but
  857.      not saved in the kill ring.
  858.      The value returned is always `nil'.
  859.  - Command: backward-delete-char-untabify COUNT &optional KILLP
  860.      This function deletes COUNT characters backward, changing tabs
  861.      into spaces.  When the next character to be deleted is a tab, it is
  862.      first replaced with the proper number of spaces to preserve
  863.      alignment and then one of those spaces is deleted instead of the
  864.      tab.  If KILLP is non-`nil', then the command saves the deleted
  865.      characters in the kill ring.
  866.      If COUNT is negative, then tabs are not changed to spaces, and the
  867.      characters are deleted by calling `delete-backward-char' with
  868.      COUNT.
  869.      In an interactive call, COUNT is the numeric prefix argument, and
  870.      KILLP is the unprocessed prefix argument.  Therefore, if a prefix
  871.      argument is supplied, the text is saved in the kill ring.  If no
  872.      prefix argument is supplied, then one character is deleted, but
  873.      not saved in the kill ring.
  874.      The value returned is always `nil'.
  875. File: elisp,  Node: User-Level Deletion,  Next: The Kill Ring,  Prev: Deletion,  Up: Text
  876. User-Level Deletion Commands
  877. ============================
  878.    This section describes higher-level commands for deleting text,
  879. commands intended primarily for the user but useful also in Lisp
  880. programs.
  881.  - Command: delete-horizontal-space
  882.      This function deletes all spaces and tabs around point.  It returns
  883.      `nil'.
  884.      In the following examples, assume that `delete-horizontal-space' is
  885.      called four times, once on each line, with point between the
  886.      second and third characters on the line.
  887.           ---------- Buffer: foo ----------
  888.           I -!-thought
  889.           I -!-     thought
  890.           We-!- thought
  891.           Yo-!-u thought
  892.           ---------- Buffer: foo ----------
  893.           
  894.           (delete-horizontal-space)   ; Four times.
  895.                => nil
  896.           
  897.           ---------- Buffer: foo ----------
  898.           Ithought
  899.           Ithought
  900.           Wethought
  901.           You thought
  902.           ---------- Buffer: foo ----------
  903.  - Command: delete-indentation &optional JOIN-FOLLOWING-P
  904.      This function joins the line point is on to the previous line,
  905.      deleting any whitespace at the join and in some cases replacing it
  906.      with one space.  If JOIN-FOLLOWING-P is non-`nil',
  907.      `delete-indentation' joins this line to the following line
  908.      instead.  The value is `nil'.
  909.      If there is a fill prefix, and the second of the lines being joined
  910.      starts with the prefix, then `delete-indentation' deletes the fill
  911.      prefix before joining the lines.
  912.      In the example below, point is located on the line starting
  913.      `events', and it makes no difference if there are trailing spaces
  914.      in the preceding line.
  915.           ---------- Buffer: foo ----------
  916.           When in the course of human
  917.           -!-    events, it becomes necessary
  918.           ---------- Buffer: foo ----------
  919.           
  920.           (delete-indentation)
  921.                => nil
  922.           
  923.           ---------- Buffer: foo ----------
  924.           When in the course of human-!- events, it becomes necessary
  925.           ---------- Buffer: foo ----------
  926.      After the lines are joined, the function `fixup-whitespace' is
  927.      responsible for deciding whether to leave a space at the junction.
  928.  - Function: fixup-whitespace
  929.      This function replaces white space between the objects on either
  930.      side of point with either one space or no space as appropriate.
  931.      It returns `nil'.
  932.      The appropriate amount of space is none at the beginning or end of
  933.      the line.  Otherwise, it is one space except when point is before a
  934.      character with close parenthesis syntax or after a character with
  935.      open parenthesis or expression-prefix syntax.  *Note Syntax Class
  936.      Table::.
  937.      In the example below, when `fixup-whitespace' is called the first
  938.      time, point is before the word `spaces' in the first line.  It is
  939.      located directly after the `(' for the second invocation.
  940.           ---------- Buffer: foo ----------
  941.           This has too many     -!-spaces
  942.           This has too many spaces at the start of (-!-   this list)
  943.           ---------- Buffer: foo ----------
  944.           (fixup-whitespace)
  945.                => nil
  946.           (fixup-whitespace)
  947.                => nil
  948.           ---------- Buffer: foo ----------
  949.           This has too many spaces
  950.           This has too many spaces at the start of (this list)
  951.           ---------- Buffer: foo ----------
  952.  - Command: just-one-space
  953.      This command replaces any spaces and tabs around point with a
  954.      single space.  It returns `nil'.
  955.  - Command: delete-blank-lines
  956.      This function deletes blank lines surrounding point.  If point is
  957.      on a blank line with one or more blank lines before or after it,
  958.      then all but one of them are deleted.  If point is on an isolated
  959.      blank line, then it is deleted.  If point is on a nonblank line,
  960.      the command deletes all blank lines following it.
  961.      A blank line is defined as a line containing only tabs and spaces.
  962.      `delete-blank-lines' returns `nil'.
  963.